Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Testing & Debugging/Mac OS Development Toolkit/Automation Essentials 2.3.0/Host Automation Folder/VU External Tool libs/AEPost.vuLib

Text File | 1998-03-19 | 17.5 KB | 411 lines | [TEXT/MPS ]

#########################################################################
#########################################################################
##                     Copyright © 1993-1997 Apple Computer, Inc.
##                                All rights reserved
#########################################################################
#########################################################################
#
#    Library:        AEPost.vulib
#
#    Version:        1.0.0
#
#    Description:    This file contains support tasks for using AEPost
#                    from a VU script.
#
#                    AEPost is an external tool for sending messages
#                    between VU scripts, AppleScript scripts, and any
#                    other Apple Event savvy application. A message
#                    is a list of simple data types, namely strings,
#                    integers, Booleans, and other lists. These types
#                    appear the same to VU and AppleScript, making
#                    real-time communication between them easy.
#
#                    To allow asynchronous sending and receiving, the
#                    messages are held in "mailboxes". Each mailbox has
#                    a unique ID. Mailbox IDs are lists of the same
#                    design as a message, but usually much shorter.
#                    Each script can "own" multiple mailboxes at any
#                    given time, although most use only one.
#
#                    There is no security in AEPost 1.0. The goal is to
#                    create a useful tool for automation, not a private
#                    e-mail system. All messages are visible if you know
#                    the mailbox ID.
#
#                    Messages are sent to mailbox IDs and received
#                    from mailbox IDs. Sending and receiving scripts
#                    have no knowledge of each other. This can lead to
#                    interesting "failures" where the sender tries to
#                    send before the receiver creates its mailbox.
#
#                    To alleviate this problem, AEPost allows
#                    senders and receivers to specify a timeout value
#                    for failures instead of failing immediately. See
#                    the individual tasks for the definitions of
#                    these timeouts.
#
#                    Before using AEPost, your VU script must call
#                    InitMessages(). To send a message to a mailbox ID,
#                    use SendMessage(), and to retreive a message (or
#                    several messages) use ReceiveMessage().
#
#    Contains:
#        VU External Tool Service Declarations
#        SendMessage()
#        ReceiveMessage()
#        InitMessages()
#
#    History:
#        10/30/94    SBR        First built with Echo service
#        08/13/95    SBR        Added to Clouseau projector database.
#        01/28/97    JAS        Added service GetThreads to this file.
#                            Added descriptions for ReadAllMail and GetThreads.
#
#    Version    When        Who    What
#    1.2.0    01/28/97    JAS    Added 'vers' resources to library.
#                            These should always match tool version when tool is revved.
#
#########################################################################
#########################################################################

tool AEPost s:'MsgS'
begin
    # Services specific to AEPost:

    # To Echo a list after a number of ticks, in a new thread
    # first parameter is the value or list of values to echo
    # second parameter is the number of ticks to pause before returning
    # third parameter is Boolean:
    #        true means beep entering and leaving ProcessRequest()
    #        false means do not
    # return value should be equal to first parameter except when:
    #        symbol and descriptor parameters are turned into strings by VU
    #        integers are sent to the tool as long or short based on VU version
    #        longs are sent to the script as long or string based on VU version
    Service    "EchoThread"( 'undefined', 'integer', 'symbol', 'integer' ) return 'undefined';

    # To Echo a list after a number of ticks, in the RequestDispatcher thread
    # same as Echo service except this one is non-threaded
    Service    "EchoNoThread"( 'undefined', 'integer', 'symbol', 'integer' ) return 'undefined';

    # To set the number of ticks given to WaitNextEvent() in the tool
    # Only affects the tool when it is in the background
    # returns the previous value
    Service    "SetSleepTicks"( 'integer' ) return 'integer';

    # To get messages from a Mailbox in the external tool (create Mailbox if needed)
    # 1st parameter is a list, the ReceiverID
    # 2nd parameter is a list, the SenderID, to filter messages to be received
    # 3rd parameter is a Boolean, true to receive all messages (even if filtered)
    #                                 false to receive one message at a time
    # 4th parameter is a Boolean, true to delete the Mailbox when service returns
    #                                 false to let the Mailbox stay
    # returns the message(s) received (a list):
    #    if Sender ID defined and 2nd param true:
    #        returns contentsList
    #    if Sender ID defined and 2nd param false:
    #        returns { contentsList1, ..., contentsListn }
    #    if Sender ID undefined and 2nd param true:
    #        returns { { SenderID1, contentsList1 }, ..., { SenderIDn, contentsListn } }
    #    if Sender ID undefined and 2nd param false:
    #        returns { SenderID, contentsList }
    Service    "MsgReceive"( 'list', 'list', 'symbol', 'symbol'  ) return 'undefined';

    # To get messages from a Mailbox in the external tool (create Mailbox if needed)
    # 1st parameter is a list, the ReceiverID
    # 2nd parameter is a list, the SenderID, to filter messages to be received
    # 3rd parameter is a Boolean, true to receive all messages (even if filtered)
    #                                 false to receive one message at a time
    # 4th parameter is a Boolean, true to delete the Mailbox when service returns
    #                                 false to let the Mailbox stay
    # 5th parameter is an Integer,    >0 is seconds to wait until a message is received
    #                                 =0 to return immediately whether message or not
    # returns the message(s) received (a list):
    #    if Sender ID defined and 2nd param true:
    #        returns contentsList
    #    if Sender ID defined and 2nd param false:
    #        returns { contentsList1, ..., contentsListn }
    #    if Sender ID undefined and 2nd param true:
    #        returns { { SenderID1, contentsList1 }, ..., { SenderIDn, contentsListn } }
    #    if Sender ID undefined and 2nd param false:
    #        returns { SenderID, contentsList }
    Service    "MsgReceiveThread"( 'list', 'list', 'symbol', 'symbol', 'integer'  ) return 'undefined';

    # To send a message to an existing Mailbox
    # 1st parameter is the ReceiverID list
    # 2nd parameter is the SenderID list
    # 3rd parameter is the contents list
    # 4th parameter is a Boolean:
    #    true means create a Mailbox with ID = ReceiverID (for the expected reply)
    #    false means do not create a Mailbox (no reply expected)
    # returns true if the message was sent, otherwise returns error value
    Service    "MsgSend"( 'list', 'list', 'list', 'symbol' ) return 'undefined';

    # To send a message to Mailbox that may not exist yet
    # 1st parameter is the ReceiverID list
    # 2nd parameter is the SenderID list
    # 3rd parameter is the contents list
    # 4th parameter is a Boolean:
    #    true means create a Mailbox with ID = ReceiverID (for the expected reply)
    #    false means do not create a Mailbox (no reply expected)
    # 5th parameter is an integer (WaitForSend):
    #    >0 is seconds to wait for receiver mailbox to appear
    #    =0 means return error if receiver mailbox is not already there
    # 6th parameter is an integer (WaitForReceipt):
    #    >0 is seconds to wait for receiver to read the message
    #    =0 means do not wait for receiver to read the message
    # 7th parameter is an integer (WaitForReply):
    #    >0 is seconds to wait for one message from the receiver (assumed to be the reply)
    #    =0 means do not wait for a message from the receiver (use MsgReceive service later)
    # returns true if the message was sent, otherwise returns error value
    Service    "MsgSendThread"( 'list', 'list', 'list', 'symbol',
                                    'integer', 'integer', 'integer' ) return 'undefined';

    # Read all mail in all mailboxes
    # retuns a list of all mailboxes and their contents (if any)
    # Each mailbox in the returned list is shown as follows:
    #
    #    {{mailboxID},{messageID,receiptRequested,{receiverID},{senderID},{messageContents}}}
    #
    #    mailboxID            List. The ID of this mailbox (receiver)
    #    messageID            Integer. The ID of this message. Used internally.
    #    receiptRequested    Boolean. True if a receipt requested.
    #    receiverID            List. The receiverID the message was sent to. Should match     mailboxID.
    #    senderID            List. The ID of the message sender.
    #    messageContents        List. The message itself.
    #
    # If there are no messages in a mailbox only the mailboxID is returned in the list:
    #    {{mailboxID}}
    #
    # Note: Calling ReadAllMail returns copies of the messages currently in all mailboxes,
    # it does not remove the messages.
    #
    Service "ReadAllMail" () return 'list';

    # returns a list of all threads that currently exist in the tool
    #
    # Each item in returnedValue has the form:
    #    { threadID, threadState, {threadOwnerInfo} }
    #
    #    The threadID is the ID assigned by the Thread Manager.
    #    The threadState is the Thread Manager state converted to a string.
    #    The threadOwnerInfo is a list. It contains:
    #        {threadName, {threadParameters}, threadStatus}
    #
    #        The threadName is the threaded service's name for this request,
    #        or it may be "Application" indicating the Application (main) thread,
    #        or it may be "RequestDispatcher" indicating the RequestDispatcher thread.
    #        (For more information see "VU Tool Template Design Notes.")
    #
    #        The threadParameters is a list of the parameters for this request.
    #        Currently "Application" and "RequestDispatcher" have empty lists
    #        for their threadParameters.
    #
    #    The threadStatus is an optional string that may be set at any time by
    #    the code currently executing in the thread. (For more information on
    #    designing external tools see "VU Tool Template Design Notes.")
    #
    Service "GetThreads" () return 'list';

    # To check for tool memory leaks - calls FreeMem() Memory Manager funtion.
    Service    "FreeMemory"( ) return 'integer';

end;



#########################################################################
#    task        SendMessage( pReceiverID, pSenderID, pMessage,
#                                pCreateReplyMailbox, pWaitForSend,
#                                pWaitForReceipt, pWaitForReply )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Sends pMessage to pReceiverID by using the AEPost
#                    external tool. All list parameters may contain Boolean, string,
#                    integer, and list types. This is a synchronous external tool call.
#    Parameters:        pReceiverID:    A non-empty ID list representing the mailbox
#                                    the message is sent to.
#                    pSenderID:        A non-empty ID list representing the sender
#                                    of the message.
#                    pMessage:        A list; the contents of the message. Can be empty.
#                    pCreateReplyMailbox:    Boolean, true to create a mailbox with
#                                    ID of pSenderID, which will remain after this
#                                    call returns. False will not create a mailbox.
#                    pWaitForSend:    Integer, seconds to wait for pReceiver's mailbox
#                                    to appear. Allows sending a message even when
#                                    the receiver's mailbox does not exist yet.
#                                    If pWaitForSend is zero, this task fails if the
#                                    receiver's mailbox does not exist.
#                    pWaitForReceipt:    Integer, seconds to wait for a receipt from
#                                        the receiver. A receipt for a message is
#                                        defined as reversed pSenderID and pReceiverID,
#                                        with the same internal messageID, and an empty
#                                        content list. If a message is sent with its
#                                        "receiptRequested" flag set, then when it
#                                        is disposed it creates and sends the receipt.
#                                        If pWaitForReceipt is zero, the message is not
#                                        marked as "receiptRequested".
#                    pWaitForReply:    Integer, seconds to wait for the first message
#                                    to pSenderID from pReceiverID. This is assumed
#                                    to be a reply, but it may have been there already.
#                                    If pWaitForReply is zero, this task will just return
#                                    and report whether the message was sent properly.
#                    NOTE:    The sum of (pWaitForSend + pWaitForReceipt + pWaitForReply)
#                            must not exceed 32767; it is the maximum value for
#                            the VU 2.1 ExternalToolTimeout() task.
#    Returns:        the AEPost external tool's return list
#    Examples:        SendMessage( {'thisReceiver'}, { 'theSender' }, { 1, true, 5 } );
#                    SendMessage( {'thatReceiver', 5}, { 32, 'theSender' },
#                                    { 'hello', true, { 'inner', { 1,2,3 }, true} },
#                                    false, 20, 0, 20 );
#    Assumptions:    VU 2.1, AEPost
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        04/12/95    SBR            created
#########################################################################
task SendMessage( pReceiverID, pSenderID, pMessage, pCreateReplyMailbox := false,
                        pWaitForSend := 0, pWaitForReceipt := 0, pWaitForReply := 0 )
begin
    #println "SendMessage( {pReceiverID}, {pSenderID}, {pMessage}, {pCreateReplyMailbox}, {pWaitForSend}, {pWaitForReceipt}, {pWaitForReply} )";

    if not global __gAEPostPresent
        InitMessages();

    if pWaitForSend OR pWaitForReceipt OR pWaitForReply
    begin
        tNewTimeout := 10 + pWaitForSend + pWaitForReceipt + pWaitForReply;
        if tNewTimeout > 32767
            tNewTimeout := 32767;
        tSaveTimeout := ExternalToolTimeout(tNewTimeout);

        tReturn := AEPost( 'MsgSendThread', pReceiverID, pSenderID, pMessage,
                                pCreateReplyMailbox,
                                pWaitForSend, pWaitForReceipt, pWaitForReply );

        ExternalToolTimeout(tSaveTimeout);
        return tReturn;
    end;
    else
    begin
        return AEPost( 'MsgSend', pReceiverID, pSenderID, pMessage,
                                pCreateReplyMailbox );
    end;
end;


#########################################################################
#    task        ReceiveMessage( pReceiverID, pSenderID, pReceiveMultiple,
#                                    pDeleteMailbox, pWaitForMessage )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Receives a message or list of messages.
#    Parameters:        pReceiverID:    A non-empty ID list representing the mailbox
#                                    that is searched for messages received.
#                    pSenderID:        An ID list representing the expected sender of the
#                                    message. Use empty list to receive from any sender.
#                    pReceiveMultiple:    Boolean, true to receive all the messages from
#                                    the expected sender, false to receive only one
#                                    (oldest message first).
#                    pDeleteMailbox:    Boolean, true to delete the pReceiverID mailbox
#                                    when this service completes. False to leave the
#                                    mailbox alone.
#                    pWaitForMessage:    Integer, seconds to wait for a message from
#                                        the sender. If pWaitForReceipt is zero, an
#                                        error is returned if there is no message.
#                    NOTE: The pWaitForMessage parameter must not exceed 32767; it is the
#                            maximum value for the VU 2.1 ExternalToolTimeout() task.
#    Returns:        If pSenderID is non-empty and pReceiveMultiple is false:
#                        { message1Contents }
#                    If pSenderID is non-empty and pReceiveMultiple is true:
#                        { {message1Contents}, {message2Contents}... }
#                    If pSenderID is empty and pReceiveMultiple is false:
#                        { pSenderID1, {message1Contents} }
#                    If pSenderID is empty and pReceiveMultiple is true:
#                        {    { pSenderID1, {message1Contents} },
#                            { pSenderID1, {message2Contents} },
#                            { pSenderID2, {message3Contents} }... }
#    Examples:        ReceiveMessage( {'theRcvr'}, { 'theSndr' }, false, false, false );
#                    ReceiveMessage( {'thatReceiver', 5}, { }, true, true, 121 );
#    Assumptions:    VU 2.1, AEPost
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        04/12/95    SBR            created
#########################################################################
task ReceiveMessage( pReceiverID, pSenderID, pReceiveMultiple, pDeleteMailbox := true,
                        pWaitForMessage := 0 )
begin
    #println "ReceiveMessage( {pReceiverID}, {pSenderID}, {pReceiveMultiple}, {pDeleteMailbox}, {pWaitForMessage} )";

    if not global __gAEPostPresent
        InitMessages();

    if pWaitForMessage
    begin
        tNewTimeout := 10 + pWaitForMessage;
        if tNewTimeout > 32767
            tNewTimeout := 32767;
        tSaveTimeout := ExternalToolTimeout(tNewTimeout);

        tReturn := AEPost( 'MsgReceiveThread', pReceiverID, pSenderID,
                                pReceiveMultiple, pDeleteMailbox,
                                pWaitForMessage );

        ExternalToolTimeout(tSaveTimeout);
        return tReturn;
    end;
    else
    begin
        return AEPost( 'MsgReceive', pReceiverID, pSenderID,
                                pReceiveMultiple, pDeleteMailbox );
    end;
end;


#########################################################################
#    task                    InitMessages(  )
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Determines if the AEPost external tool is running,
#                    and initializes it on the host if it isn't.
#    Parameters:        none
#    Returns:        true if AEPost is available,
#                    false if the tool could not be found, launched or initialized.
#    Examples:        InitMessages();
#    Assumptions:    VU 2.1, AEPost
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        04/12/95    SBR            created based on IsVUAidInstalled()
#########################################################################
task InitMessages( )
begin
    global __gAEPostPresent;

    if isUndefined( __gAEPostPresent )
    begin
        AEPostWasInitialized := true;
        test4AEPost := AEPost("Initialize", false);
        theScriptError := ScriptError();
        __gAEPostPresent := (test4AEPost[1] = 0);

        if theScriptError = -1223
        begin
            println 'InitMessages: AEPost external tool not found or failed to launch.';
            println 'InitMessages: Copy it to the host hard disk and rebuild the desktop file.';
        end;
        else if theScriptError = -1224
        begin
            println 'InitMessages: External tool launch failed. Is there enough memory?';
        end;
        else if not ( test4AEPost[2] ~= /≈Threading enabled≈/ )
        begin
            println 'InitMessages: Threading is not enabled, please install the Thread Manager';
        end;
    end;

    if not __gAEPostPresent
        println "InitMessages: AEPost initialization failed!";
    else
    begin
        println "InitMessages: AEPost free memory is {AEPost("Freememory")}.";
    end;

    return __gAEPostPresent;
end;